home *** CD-ROM | disk | FTP | other *** search
/ The Utilities Experience / The Utilities Experience - Volume 1.iso / software / graphics / n-z / xanim4 / xanim.readme < prev    next >
Text File  |  1995-12-21  |  35KB  |  884 lines

  1.  
  2. XAnim Rev 2.69.7.5  19Jan95
  3.  
  4. COMPILING ON UNIX Systems (SunOS,Solaris,HP/UX,DG/UX,AIX,
  5.                Linux,Ultrix,OSF/1,etc)
  6.  
  7.  
  8.   If you have Imake on your system you can type
  9.  
  10.     xmkmf
  11.  
  12.   which should produce a Makefile from the Imakefile. Then
  13.   you can type:
  14.  
  15.     make xanim
  16.   
  17.   If this doesn't work you can copy Makefile.unx to Makefile.
  18.   Edit the Makefile and specify where the X11 includes and 
  19.   X11 libraries are on your particular machine. Then type
  20.  
  21.     make xanim
  22.  
  23.   NOTE: That in the Imakefile, XCOMM is used as a comment. This
  24.   is recommended by X11R6, but may break older revs. To fix,
  25.   simply replace every occurence of "XCOMM" with "#" in the
  26.   Imakefile. See top of Imakefile for more details.
  27.  
  28.  
  29. COMPILING ON VMS/AXP Systems
  30.   The files make.com and xanimXX.opt are provided for VMS users.
  31.   make.com should correctly detect wether you're running
  32.   DECWindows XUI or DECWindows MOTIF(revs 1.1 and 1.2) and use
  33.   the appropriate xanimXX.opt file.
  34.  
  35.   If you use the VMS MMS (or "make") facility, then a descript.mms
  36.   file is provided.
  37.  
  38.   NOTE: since VMS is case insensitve, all options to xanim must be
  39.   enclosed in double quotes in order for them to be proper recognized.
  40.   Example:
  41.         xanim "+bCn" anim1 anim2
  42.  
  43.  
  44. HOW TO USE XANIM
  45. The following is a copy of the man page with examples at the end.
  46.  
  47. SYNOPSIS
  48.      xanim [ +Vnum ] [ +Aaopts ]  [  +Ccopts  ]  [  +Ggopts  ]  [
  49.           +Mmopts  ] [ +Ssopts ] [ +opts ] animfile [ [ +opts ] [
  50.           animfile ] ... ]
  51.  
  52. DESCRIPTION
  53.      XAnim is a program that can display  animations  of  various
  54.      formats on systems running X11. XAnim currently supports the
  55.      following animation types:
  56.  
  57.       +  FLI animations.
  58.       +  FLC animations.
  59.       +  IFF animations.  The  following  features  are  sup-
  60.          ported:
  61.            -> Compressions 3,5,7,J(movies) and l(small L).
  62.            -> Color cycling during single images and anims.
  63.            -> Display Modes: depth 1-8, EHB, HAM and HAM8.
  64.       +  GIF87a and GIF89a files.
  65.            -> single and multiple images supported.
  66.            -> GIF89a animation extensions supported.
  67.       +  GIF89a animation extension support.
  68.       +  a kludgy text file listing gifs and  what  order  to
  69.          show them in.
  70.       +  DL animations. Formats 1, 2 and 3. TEMPORARILY DISABLED.
  71.       +  Amiga PFX(PageFlipper Plus F/X) animations. DISABLED TEMPORARILY.
  72.       +  Amiga MovieSetter animations(For those Eric Schwartz
  73.          fans).
  74.       +  Utah Raster Toolkit RLE images and anims.
  75.       +  AVI animations. Currently supported are
  76.            ->*IBM Ultimotion     (ULTI) depth 16.
  77.                -> JPEG               (JPEG) depth 24.
  78.                -> Motion JPEG        (MJPG) depth 24.
  79.                -> Intergraph JPEG    (IJPG) depth 24.
  80.            -> Microsoft Video 1  (CRAM) depth 8 and 16.
  81.            -> SuperMac Cinepak   (CVID) depth 24.
  82.            -> Uncompressed       (RGB ) depth 8
  83.            -> Run length encoded (RLE8) depth 8.
  84.       +  Quicktime Animations.  The  following  features  are
  85.          supported:
  86.            -> Uncompressed     (RAW ) depth 4,8,16,24,24+ and GRAY 4,8.
  87.            -> Apple Graphics   (RLE ) depth 1,8,16 and 24 and GRAY 8.
  88.            -> Apple Animation  (SMC ) depth 8 and GRAY.
  89.            -> Apple Video      (RPZA) depth 16.
  90.            -> SuperMac Cinepak (CVID) depth 24 and GRAY 8.
  91.            -> ???      YUV2    (YUV2) depth 24.
  92.            -> Photo JPEG       (JPEG) depth 8 and 24.
  93.            -> Supports multiple video trak's.
  94.            -> Supports animations with multiple codecs.
  95.            -> Supports single-fork and separate .rsrc and .data forks.
  96.       +  JFIF images. NOTE: use XV for single images. This is more
  97.          for animation of a sequence of JPEG images.
  98.       +  WAV audio files may have their sound added to any animation
  99.          type that doesn't already have audio, by specifying the .wav
  100.          file after the animation file on the command line. Currently
  101.          only the PCM audio codec is supported.
  102.       +  any combination of the above  on  the  same  command
  103.          line.
  104.  
  105. ---------------------------------------------------------------------------
  106. * The following copyright applies to all Ultimotion segments of the code:
  107.  
  108.   "Copyright International Business Machines Corporation 1994, All rights
  109.    reserved. This product uses Ultimotion(tm) IBM video technology."
  110. ---------------------------------------------------------------------------
  111.  
  112.      XAnim also provides various options that allow the  user  to
  113.      alter colormaps, playback speeds, looping modes and can pro-
  114.      vide on-the-fly scaling of animations with the mouse.
  115.  
  116. OPTIONS
  117.      A + will generally turn an option on and a -  will  turn  an
  118.      option  off.   This  can  be  reversed at compile time. (see
  119.      xanim_config.h).
  120.  
  121.      In each SubMenu, the options can be  run  together  with  no
  122.      intervening spaces. In the list of SubMenu options presented
  123.      below, the first letter given is the letter  that  specifies
  124.      the  SubMenu  and  should NOT be repeated if several SubMenu
  125.      options are to be run together.
  126.  
  127.      For example,  "+Cn  +Cs10  +CF4"  can  also  be  written  as
  128.      "+Cns10F4" or "+CF4s10n".
  129.  
  130.      A + or a - within a SubMenu will be an exit from  that  sub-
  131.      menu.   Options  will  affect  all  animations following the
  132.      invocation of that option. Some options may  be  changed  in
  133.      between animations without affecting previous animations.
  134.  
  135.      In the following sections,  an  "num"  represents  an  integer
  136.      number and an "fnum" represents a floating point number. Don't
  137.      include the double quotes. If a floating point number is of an 
  138.      integer amount, the "." need not be specified. There should be
  139.      no spaces between the option and the numbers.
  140.  
  141.      aopts SubMenu for Audio Options
  142.  
  143.       +Ae        Audio Enable. XAnim will ignore audio data if
  144.             this option is not used.
  145.  
  146.       +Ak        This option allows XAnim to skip video frames
  147.             in order to help keep video in sync with audio.
  148.             default is on.
  149.  
  150.       +As"fnum"    Scale Audio playback speed by "fnum". Only the
  151.             range 0.125 to 8.00 is allowed.
  152.             NOTE: CURRENTLY VIDEO DOESN'T SCALE WITH AUDIO.
  153.  
  154.       +Ap"num"    This turns a hardware specific Audio port on or off.
  155.                Port 0 - main speaker (on  by default)
  156.                Port 1 - headphones   (off by default)
  157.                Port 2 - line out     (off by default)
  158.  
  159.       +Av"num"    Sets the inital Audio Volume(0-100) with 0
  160.             the lowest. default is 40.
  161.  
  162.      copts SubMenu for Color Options
  163.  
  164.       +C1        Create a colormap from the  first  frame  of  a
  165.             TrueColor  anim  and  then  remap the remaining
  166.             frames to this colormap. This  can  potentially
  167.             add  significant time to the startup of an ani-
  168.             mation but usually results  in  better  colors.
  169.             The  animation  needs  to  be buffered for this
  170.             option to work.  Not  valid  for  TrueColor  or
  171.             DirectColor displays(nor is it needed).
  172.  
  173.       +C3        Convert TrueColor  anims  to  332(StaticColor).
  174.             TrueColor  anims  are  animations  that provide
  175.             separate RGB info for each pixel,  rather  than
  176.             each  pixel being an index into a global color-
  177.             map. AVI(16bit CRAM), QT(RPZA and RLE depth  16
  178.             and  24)  and URT RLE 24 bit anims are examples
  179.             of TrueColor anims. This option is ignored  for
  180.             TrueColor or DirectColor displays.
  181.  
  182.       +CA         Create  a  colormap  from  each  frame   of   a
  183.             TrueColor  anim.  This  can  be  useful  if the
  184.             colors radically change during  the  course  of
  185.             the  animation.  This can take a VERY,VERY long
  186.             time at start up. Animation must  be  buffered.
  187.             This   option   is  ignored  for  TrueColor  or
  188.             DirectColor displays.
  189.  
  190.       +Ca         Remap all images to  single  new  cmap  created
  191.             from all of the colormaps.
  192.  
  193.       +Cd         Use Floyd-Steinberg  dithering  if  needed  for
  194.             non-monochrome  displays.   This  will  cause a
  195.             reduction in playback speed.
  196.  
  197.       +Cf         Forcibly remap to all  frames  to  1st  frame's
  198.             cmap.
  199.  
  200.       +CF0          Turns off CF4 option.
  201.  
  202.       +CF4          This option samples the colors of true color
  203.             animations ahead of time and forms a color
  204.             lookup table.  Beats the just truncating to a
  205.             RGB 332 color table and IMHO beats dithering.
  206.             See the +s option below(also in copts submenu).
  207.             Currently ONLY Work with unbuffered animations
  208.  
  209.       +Cg         Convert TrueColor anims  to  gray  scale.  This
  210.             option is ignored for TrueColor and DirectColor
  211.             displays.
  212.  
  213.       +Ch         Use histogram to aid in color  reduction.  His-
  214.             trogramming  is  only  done  on frames that are
  215.             buffered.
  216.  
  217.       +Cm         This option is currently needed if you want  to
  218.             dither  TrueColor anims to a 332 colormap. Ani-
  219.             mation must be buffered.  Typically  +bC3dm  is
  220.             the  option  to  use. This can take a VERY long
  221.             time at start up.
  222.  
  223.       +Cn         Don't create new colormap but instead  allocate
  224.             colors from the X11 Display's default cmap.
  225.  
  226.       +Cs"num"    This is the number of frames the +CF4 option looks
  227.             at ahead of time. More frames potentially yields
  228.             better colors results, but takes more time at
  229.             start up.  default is 5.
  230.  
  231.      gopts SubMenu for Gamma Options
  232.  
  233.       +Ga"fnum"    Set gamma of animation to be displayed.
  234.  
  235.       +Gd"fnum"    Set gamma of display. 1.0 is no change. gamma's
  236.             greater  than 1.0 typically brighten the anima-
  237.             tion.
  238.  
  239.      mopts SubMenu for Median-Cut Quantization Options
  240.  
  241.       +Ma        compute box color from average of box.
  242.  
  243.       +Mc        compute box color as center of box.
  244.  
  245.       +Mb"num"    Truncate rgb to "num" bits before quantizing.
  246.  
  247.      sopts SubMenu for Scaling Options
  248.  
  249.       +Si        Half the  height  of  IFF  anims  if  they  are
  250.             interlaced.(Not  completely  reliable since not
  251.             all IFF anims correctly identify themselves  as
  252.             interlaced).
  253.  
  254.       +Sn        Prevents X11  window  from  resizing  to  match
  255.             animations's size.
  256.  
  257.       +Sr        Allow user to  resize  animation  on  the  fly.
  258.             Enlarging an animation can greatly reduce play-
  259.             back speed depending on the power of the cpu.
  260.  
  261.       +Ss"fnum"    Scale the size  of  animation  by  "fnum"  before
  262.             displaying.
  263.  
  264.       +Sh"fnum"    Scale the horizontal size of the  animation  by
  265.             "fnum" before displaying.
  266.  
  267.       +Sv"fnum"    Scale the vertical size  of  the  animation  by
  268.             "fnum" before displaying.
  269.  
  270.       +Sx"num"    Scale the animation to have  width  "num"  before
  271.             displaying.
  272.  
  273.       +Sy"num"    Scale the animation to have height  "num"  before
  274.             displaying.
  275.  
  276.       +Sc        Copy display scaling factors to display buffer-
  277.             ing factors.
  278.  
  279.       +SS"fnum"    Scale the size of the animation by "fnum"  before
  280.             buffering it.
  281.  
  282.       +SH"fnum"    Scale the horizontal size of the  animation  by
  283.             "fnum" before buffering it.
  284.  
  285.       +SV"fnum"    Scale the vertical size  of  the  animation  by
  286.             "fnum" before buffering it.
  287.  
  288.       +SX"num"    Scale the animation to have  width  "num"  before
  289.             buffering it.
  290.  
  291.       +SY"num"    Scale the animation to have height  "num"  before
  292.             buffering it.
  293.  
  294.       +SC        Copy buffer scaling factors to display  scaling
  295.             factors.
  296.  
  297.      zopts SubMenu for Special Options
  298.  
  299.  
  300.       +Ze        XAnim will exit after playing  through  command
  301.             line once.
  302.  
  303.       +Zp"num"    XAnim pause at frame "num" and then wait for user
  304.             input.  Several  pauses  may be specified. Each
  305.             group of pauses will only affect the  animation
  306.             immediately following them on the command line.
  307.             Pauses will occur at least once.
  308.  
  309.       +Zr        This option enables the Remote Control  Window.
  310.             This  overrides  the  default  condition set in
  311.             xanim_config.h. Remote Control support must  be
  312.             compiled into XAnim for this to work.
  313.  
  314.  
  315.      Normal Options
  316.  
  317.       +b        Uncompress and buffer images before displaying.
  318.             This only applies to AVI,QT, IFF,FLI,FLC anima-
  319.             tions. The rest(GIF87a,GIF89a,DL,PFX  and  RLE)
  320.             are currently always uncompressed and buffered.
  321.             This is cleared by the +f option.
  322.  
  323.       +B        Used X11 Shared Memory(if present)for unbuffered
  324.             animations only.(This is mutually exclusive with
  325.             +b above).
  326.  
  327.       +f        Don't load anim into memory, but read each sec-
  328.             tion  only  when needed. This is supported only
  329.             for AVI,QT,IFF,FLI  and  FLC  animations.  This
  330.             option  is cleared by the +b option. This saves
  331.             memory at the cost of speed.
  332.  
  333.       +c        let xanim know that iff anim  is  a  nonlooping
  334.             one.
  335.  
  336.       +d"num"    debug switch. "num" can be from 0(off) to 5(most)
  337.             for level of detail.
  338.  
  339.       +F        Floyd-Steinberg dithering when needed.
  340.  
  341.       +j"num"    "num"  is  the  number  of  milliseconds  between
  342.             frames.  if  0  then  the time specified in the
  343.             animation is used for timing purposes.
  344.  
  345.       +l"num"    loop animation "num" number of times before  mov-
  346.             ing on to next animation.
  347.  
  348.       +lp"num"    ping-pong animation "num" number of times  before
  349.             moving on to next animation.
  350.  
  351.       +N        don't display images. Useful for benchmarking.
  352.  
  353.       +o        turns    on    certain    optimizations.    See
  354.             xanim.readme.
  355.  
  356.       +p        Use Pixmap instead of Image in X11. This option
  357.             has    no    effect   if   the   animation   is
  358.             buffered(either  by  default  or  with  the  +b
  359.             option).
  360.  
  361.       +r        Allow color cycling for IFF single images.
  362.  
  363.       +R        Allow color cycling  for  IFF  anims.  (default
  364.             should be off)
  365.  
  366.       +T0        Title option 0. Title is just XAnim.
  367.  
  368.       +T1        Title option 1. Title  is  current  anim  name.
  369.             When  anim is stopped, the current frame number
  370.             is included.
  371.  
  372.       +T2        Title option 2. Title is current anim name  and
  373.             current frame number.
  374.  
  375.       +v        Verbose mode. Gives some information about ani-
  376.             mation such as size, number of frames, etc.
  377.  
  378.       +V"num"    Select X11 Visual to use when displaying anima-
  379.             tion.  The  "num"  is  obtained  by  using the +X
  380.             option of xanim.
  381.  
  382.       +Vclass    Select the best X11 Visual of Class class  when
  383.             displaying  the  animation. class can be anyone
  384.             of the following strings and is  case  insensi-
  385.             tive. (ie StaTicGraY is same as staticgray).
  386.  
  387.             staticgray    Select best StaticGray Visual.
  388.             grayscale     Select best GrayScale Visual.
  389.             staticcolor   Select best StaticColor Visual.
  390.             pseudocolor   Select best PseudoColor Visual.
  391.             truecolor     Select best TrueColor Visual.
  392.             directcolor   Select best DirectColor Visual.
  393.  
  394.       +X        X11 verbose mode. Display information about the
  395.             support X11 visuals.
  396.  
  397.  
  398.  
  399.  
  400. WINDOW COMMANDS
  401.      Once the animation is up and running there are various  com-
  402.      mands  that  can  be entered into that animation window from
  403.      the keyboard.
  404.  
  405.      q         quit.
  406.  
  407.      Q         Quit.
  408.  
  409.      g         Stop color cycling.
  410.  
  411.      r         Restore original Colors(useful after g).
  412.  
  413.      w         Restore original window size(useful after resizing).
  414.  
  415.      z         This pops up or removes the Remote Control Window.
  416.                Remote Control support must be compiled into XAnim
  417.                for this to work.
  418.  
  419.      <space>   Toggle. starts/stops animation.
  420.  
  421.      ,         Single step back one frame.
  422.  
  423.      .         Single step forward one frame.
  424.  
  425.      <         Go back to start of previous anim.
  426.  
  427.      >         Go forward to start of next anim.
  428.  
  429.      m         Single step back one frame staying within anim.
  430.  
  431.      /         Single step forward one frame staying within anim.
  432.  
  433.      -         Increase animation playback speed.
  434.  
  435.      =         Decrease animation playback speed.
  436.  
  437.      0         Reset animation playback speed to original values.
  438.  
  439.      AUDIO RELATED WINDOW COMMANDS
  440.  
  441.      1           Decrement volume by 10.
  442.  
  443.      2           Decrement volume by 1.
  444.  
  445.      3           Increment volume by 1.
  446.  
  447.      4           Increment volume by 10.
  448.  
  449.      s           Toggle. Audio Volume(MUTE). on/off.
  450.  
  451.      8           Toggle. Main Speaker. on/off.
  452.  
  453.      9           Toggle. Headphones. on/off.
  454.  
  455.  
  456. MOUSE BUTTONS
  457.      Once the animation is up and running the mouse buttons  have
  458.      the following functions.
  459.  
  460.      <Left_Button>
  461.            Single step back one frame.
  462.  
  463.      <Middle_Button>
  464.            Toggle. starts/stops animation.
  465.  
  466.      <Right_Button>
  467.            Single step forward one frame.
  468.  
  469. BUFFERING, PIXMAPS and READ_FROM_FILE Options
  470.      XAnim by default will read the entire animation into memory.
  471.      DL,  PFX,  Moviesetter,  GIF  or URT RLE type animations are
  472.      always uncompressed  and  stored  in  memory  as  individual
  473.      images.
  474.  
  475.      For  the  AVI,  QT,  IFF,  FLI/FLC  animations,   only   the
  476.      compressed   delta   is   stored.   These  deltas  are  then
  477.      uncompressed each time they need to be displayed. The buffer
  478.      option(+b)  may  be used to potentially speed up playback by
  479.      uncompressing and storing these images ahead  of  time.  But
  480.      more memory is used up in the process.
  481.  
  482.      When an XPutImage is called, the image typically gets copied
  483.      twice,  once to memory and then from there onto the display.
  484.      A pixmap is directly copied onto  the  display  without  the
  485.      first  copy.  This is why it is sometimes much faster to use
  486.      the pixmap option(+p).  Each image isn't  converted  into  a
  487.      pixmap until the first time it is displayed. This is why the
  488.      first loop of an animation using this  option  is  sometimes
  489.      slower  than  subsequent  loops. While the pixmap option may
  490.      improve playback speed, it will slow things down if  on-the-
  491.      fly  scaling needs to be performed. This is because XAnim no
  492.      longer has direct access to the image and  needs  to  get  a
  493.      copy of it before it can be scaled.
  494.  
  495.      The read from file option(+f) causes xanim not to store  the
  496.      compressed  deltas in memory. Instead as each image is to be
  497.      displayed, xanim reads the  corresponding  compressed  delta
  498.      from  the  file, expands it and then displays it. While this
  499.      can dramatically cut down on  memory  usage,  the  necessary
  500.      reads  from  disk(or whatever) can slow down playback speed.
  501.      XAnim still needs to allocate one  to  three  image  buffers
  502.      depending  on  the type of animation and the scaling options
  503.      used. This option is only supported for AVI, QT, FLI/FLC and
  504.      IFF  animations.  The  BODY  chunk  of IFF animations is not
  505.      included in this. As a result, an IFF animation that is made
  506.      up  of  several  BODY chunks will not currently benefit from
  507.      this option.
  508.  
  509.  
  510. SCALING Options
  511.      There are two sets of scaling options. One set, the  display
  512.      scaling factors,  affects the size of the animation as it is
  513.      displayed. The other set, the buffer scaling factors, affect
  514.      the   size   of   the   images   as   they   are  stored  in
  515.      memory(buffered). The buffer  scaling  factors  only  affect
  516.      animations  that  are  buffered  and can greatly increase or
  517.      decrease memory usage.
  518.  
  519.      These two sets are completely independent of each other. You
  520.      can  set  the  buffer scaling factors to 20 times the normal
  521.      animation size and not affect the size at which that  anima-
  522.      tion  is  displayed.  The  images are stored at 20 times the
  523.      normal size(and at 400 times the memory usage), but then get
  524.      scaled  back  down  to  normal  size before being displayed.
  525.      NOTE: that an animation must be buffered in  order  for  the
  526.      buffer scaling factors to have any affect on it. The display
  527.      scaling factors affect all animations.
  528.  
  529.      You can create pixellation like  affects  by  buffering  the
  530.      animation  at  1/8 it's normal size, but keeping the display
  531.      scaling factors at the original size. (IE  "xanim  +bSS0.125
  532.      anim.anim").
  533.  
  534.      Many times it's faster to store  and  display  an  animation
  535.      with large dimensions at half-size. The option "+bSS0.5C" or
  536.      "+bSS0.5s0.5" both will accomplish this. To save memory, you
  537.      could  even store the animation at half size and yet display
  538.      it at full size. "+bSS0.5" will accomplish this.
  539.  
  540. FORWARDS, BACKWARDS and OPTIMIZATION.
  541.      Many type of animations(FLI/FLC/IFF/some AVI  and  QTs)  are
  542.      compressed  with  forward  playback in mind only. Each delta
  543.      only stores the difference between the current frame and the
  544.      previous frame. As a results, most of these animations don't
  545.      display correctly when played backwards.  Even when buffered
  546.      up, these may not work, since XAnim only stores the smallest
  547.      rectangle that encompasses the  changes  from  the  previous
  548.      frame.  You  can  force  XAnim  to store the entire frame by
  549.      specifying the "-o" option to turn  this  optimization  off.
  550.      This will most likely use more memory and slow down the ani-
  551.      mation, since more of the image needs to  be  stored  and/or
  552.      displayed.
  553.  
  554. COLOR OPTIONS
  555.      Most of this will be a TBD for a future rev and what's  here
  556.      might be sketchy, incomplete or just plain confusing.
  557.  
  558.      TrueColor and DirectColor displays don't need to worry about
  559.      most of these options, as the animations can be displayed in
  560.      their original colors(ignoring monitor variations etc). How-
  561.      ever,  TrueColor  and  DirectColor  displays  can't  display
  562.  
  563.      animations that employ color cycling  techniques  where  the
  564.      colormap  changes  from  frame  to frame.  DirectColor could
  565.      potentially support this, but not TrueColor.
  566.  
  567.      For the rest of the displays, the problem  becomes  matching
  568.      the  colors in the animations to the available colors of the
  569.      Display.  For  most  PseudoColor  displays  this  means  256
  570.      colors.  Many  of  which are already in use by various other
  571.      programs. XAnim defaults to creating it's own  colormap  and
  572.      using  all  the  colors  from  that. The window manager then
  573.      installs this new colormap, whenever the  mouse  pointer  is
  574.      inside  the  XAnim  animation  window(Sometimes  a  specific
  575.      action is required to change the ColorMap Focus, like click-
  576.      ing  in the window or pressing a specific key). In any case,
  577.      this action usually causes  all  the  other  colors  on  the
  578.      screen  to  be  temporarily  "messed-up"  until the mouse is
  579.      moved out of the animation window. The  alternative,  is  to
  580.      use  the  "+Cn"  option.  Now XAnim tries allocating all the
  581.      colors it needs from the current colormap. If it can't get a
  582.      certain color, then XAnim choose one that is "close" to this
  583.      certain color. Close is completely arbitrary. The  animation
  584.      is  now displayed in colors that are different than the ori-
  585.      ginal colors. This difference may or may not be noticeable.
  586.  
  587.      Another big problem is when the animations are what I called
  588.      TrueColor animations. Where each pixel is stored as RGB tri-
  589.      plets. For example, AVI 16 bit CRAM animations.  Each  pixel
  590.      has  5  bits of Red, 5 bits of Green and 5 bits of Blue info
  591.      associated with it. This means there  can  be  up  to  32768
  592.      unique  colors  in  each  image.  And  on  most  PseudoColor
  593.      displays we can only display 256 unique colors. Beside  get-
  594.      ting  better  displays,  what  can  we do? XAnim defaults to
  595.      truncating the RGB information from 555 to 332. That is to 3
  596.      bits  of  Red,  3  bits of Green and 2 bits of Blue. Less on
  597.      Blue because the human eye is  more  sensitive  to  Red  and
  598.      Green than Blue.  This 332 colormap happens to be 256 colors
  599.      in size, which nicely fits  in  with  our  display.  If  our
  600.      display  only  had  64 colors, then XAnim is smart enough to
  601.      truncate things down to 222. Now the problem is  the  colors
  602.      of the displayed anim are noticeably different than the ori-
  603.      ginal colors.  Typically you  can  see  color  banding  etc.
  604.      While  this  is fine to get a feel for the animation, we can
  605.      do better. One of the solutions XAnim  currently  offers  is
  606.      the "+bC1" option. What this does is choose the the best 256
  607.      colors from the first image  of  the  animation.  Then  each
  608.      pixel  of  each subsequent image is remapped to one of these
  609.      256 colors.  This takes up some CPU time up front  and  more
  610.      memory since each image needs to be buffered, but results in
  611.      a colors that are closer to the originals.  Another  option,
  612.      "+bCA",  chooses  the  best  256  from  each image, then 256
  613.      colors from all these colormaps  are  chosen  as  the  final
  614.      colormap.   This  is useful if the colors in the first image
  615.      aren't representative of the rest of the animation. This can
  616.      be  very  slow.  Another  option  that is supported, but not
  617.      really optimized for yet is "+bC3dm". This causes  XAnim  to
  618.      use  a  332 colormap and then apply a Floyd-Steinberg dither
  619.      algorithm to each image.  Currently this is very slow.  Dif-
  620.      ferent  dithers(like Ordered) and better optimizations might
  621.      speed this up  in  future  revs.  In  general,  handling  of
  622.      TrueColor animations in XAnim needs to be improved.
  623.  
  624.      Another scenario where colors need to be remapped,  is  when
  625.      several  images  or animations with different colormaps need
  626.      to be displayed.  Changing the colormap usually  results  in
  627.      an annoying flicker. One solution to this is to remap all of
  628.      the images/animations to the same colormap. The "+Ca" option
  629.      chooses  the  best  colors  from  all the colormaps and then
  630.      remaps all the images to it. The "+Cf" option, simply remaps
  631.      everything  to the first colormap.  The "+Ch" option is use-
  632.      ful when an animation's colormap specifies a lot  of  colors
  633.      that aren't used. XAnim looks through each buffered image of
  634.      the animation and makes a histogram of the  useage  of  each
  635.      color.  This  information  is then used to weedout unused or
  636.      rarely used colors.
  637.  
  638. QUICKTIME ANIMATIONS
  639.      Quicktime animations are  usually  stored  in  two  separate
  640.      files.  One is call a data fork and ends with a ".data". The
  641.      other is a resource fork and ends in  a  ".rsrc".  Sometimes
  642.      these  animations  are in a "flattened" format, where every-
  643.      thing is put into one file. There's no standard naming  for-
  644.      mat for these types of files.
  645.  
  646.      For example, if you have a quicktime animation  made  up  of
  647.      two  files  named:  "spin.rsrc"  and  "spin.data",   you can
  648.      display them using Xanim with either of the  following  com-
  649.      mands  "xanim  spin"  or  "xanim spin.rsrc".  XAnim is smart
  650.      enough to add/modfiy the  ".rsrc"  and  ".data"  endings  as
  651.      needed.
  652.  
  653.      If you use AUFS from the Columbia  Appletalk  Package,  then
  654.      Macintosh  files have their data fork stored in the expected
  655.      place, and the resource fork is in a file with the same name
  656.      in a  .resource subdirectory. Therefore, if the data fork is
  657.      in "spin", and the resource fork isin  ".resource/spin", the
  658.      movie can be displayed with "xanim spin".
  659.  
  660.      For "flattened" quicktime animations, you  need  to  specify
  661.      the entire file name.
  662.  
  663.      NOTE: XAnim may not support all SMC or RPZA quicktime anima-
  664.      tions. It'll print "unknown code variation XX" to the screen
  665.      as it encounters these and move on to the next image of that
  666.      animation.
  667.  
  668.  
  669. EXAMPLES:
  670.     To display a single animation with Audio:
  671.  
  672.         xanim +Ae car_race.avi
  673.  
  674.     To display a audio animation on Sparc. main speakers off
  675.     and  headphones on:
  676.  
  677.         xanim +Aep1 -Ap0 car_race.avi
  678.  
  679.     To display a single animation:
  680.  
  681.         xanim iff3.anim
  682.  
  683.     To display a nonlooping IFF animation:
  684.  
  685.         xanim +c iff3.anim
  686.  
  687.     To display A.fli 3 times, B.anim and C.movie 2 times each and D.fli
  688.     once before repeating:
  689.  
  690.         xanim -l3 A.fli -l2 B.anim C.movie -l1 D.fli
  691.  
  692.     To see A.anim real slow(2 seconds for each frame):
  693.  
  694.         xanim +j2000 A.anim
  695.  
  696.     To display title image for a while then run an animation at
  697.     normal speed:
  698.  
  699.         xanim +j2000 title.gif +j0 anim.gifanim
  700.  
  701.  
  702. A series of GIF's can be displayed as:
  703.  
  704.     xanim im_0.gif im_1.gif im_2.gif ... im_36.gif
  705.  
  706.  or
  707.  
  708.     xanim im_*.gif
  709.  
  710.  or
  711.  
  712.     xanim im.txt
  713.  
  714.  or
  715.  
  716.     xanim im.gifanim
  717.  
  718. where im.txt is a txt file(a list of images, see xanim.doc for more details).
  719. and im.gifanim is one gif file composed of im_0.gif through im_36.gif.
  720. (see txtmerge to create a single gif file from a txt file).
  721.  
  722. X11 Notes:
  723. --------------------------------------
  724.  I. X11 Server Options
  725.  
  726.    When XAnim opens the display it passes the argument list to X11 which
  727.    then filters off the arguments it recognizes. XAnim won't even see these
  728.    arguments(which is sometimes a problem). For instance
  729.  
  730.    xa -geom =+100+100 skier.fli
  731.  
  732.    will play the anim skier.fli at pos <100,100> on the X11 screen.  Or
  733.  
  734.    xa -display nantucket:0.0 skier.fli
  735.  
  736.    will display the anim skier.fli on the machine nantucket's display.
  737.  
  738.    Sometimes this is a problem, because a valid XAnim option is stripped by the
  739.    X11 server. For instance if +r was being stripped, then use ++r instead.
  740.    Same goes with -r. Use --r instead if you believe it's being filtered
  741.    by X11.
  742.  
  743. Machine Specific and Compiler Notes:
  744. --------------------------------------
  745.  Some PC's need you to uncomment the line below in Makefile.
  746.  #XA_INET_LIB = -linet
  747.  
  748.  Depending on your window manager(mwm,uwm,olwm,twm etc), you might
  749.  want to have XAnim do a XInstallColormap. This shouldn't be necessary
  750.  for most workstations and can cause core dumps on some PCs.
  751.  There are usually user selectable options for each window manager
  752.  that selects the colormap focus policy(pointer,fixed,explicit etc).
  753.  Use -DNO_INSTALL in Makefile if you DON't want XAnim to install
  754.  the colormap.
  755.  
  756.  Some X11's don't have support for multiple visuals.  An executable
  757.  compiled with such an X11 will not be able to correctly run on a
  758.  machine that does supports multiple visuals even if they're binary
  759.  compatible.
  760.  
  761.  Hugh D.R. Evans has supplied make.com, xanim.opt and added VMS defines
  762.  so that VMS users may compile and run XAnim. Rick Dyson has provided
  763.  the descript.mms file and some VMS fixes. John Kneitz has also
  764.  provide some VMS fixes and suggestions.
  765.  
  766. And Yet More Notes about Quicktime Animations
  767. ---------------------------------------------
  768.         NOTES ON QUICKTIME ANIMATIONS WITH XANIM
  769.  
  770.   (these are just my notes and may contain some inconsistencies.
  771.    There's currently some question about the true meaning of
  772.    "flatten". It might just mean taking a quicktime file and
  773.    replacing a references to another files with those files
  774.    themselves.  But lately many people use it to mean collapsing
  775.    the *.data and *.rsrc forks into one *.data fork for export
  776.    to a non-mac computer. - Mark)
  777.  
  778.  
  779.    EXTRACTING Quicktime Animations
  780.  
  781.     Typically you will obtain the quicktime animations that have
  782.     been archived and then binhex'd. If the file you have ends
  783.     in a .hqx, then you need to run hexbin on it ("hexbin anim.hqx").
  784.     This will create a *.bin file(not necessarily anim.bin, it
  785.     could be anything.bin. The actual name is contained within
  786.     the *.hqx file).  
  787.  
  788.     If the file you have ends in a .bin or you've just hexbin'd a file, 
  789.     now you need to unpack it. In other words extract the files that
  790.     are contained within it. These files can be programs/documents/
  791.     animations/images etc. They're not necessarily quicktime animations.
  792.  
  793.     There is a program called macunpack that should be used to
  794.     accomplish this. You need to use the -f option, I recommend
  795.     the -lv options as well. (ie "macunpack -flv file.bin")
  796.  
  797.     Macunpack doesn't support certain DiskDoubler or Stuffit Deluxe
  798.     archives. There is no unix/pc program that I know of that does(except 
  799.     for the Mac). In this case your only choice is to get a hold of a 
  800.     Macintosh computer and someone who knows how to use it and
  801.     hopefully some method of transferring files to/from it.
  802.  
  803.     Once you've unpacked everything, you should have three files,
  804.     a *.info, a *.rsrc and a *.data. You can delete the *.info file.
  805.     XAnim doesn't need or use it.
  806.  
  807.     The quicktime animation is made up of BOTH the *.rsrc and the
  808.     *.data files and therefore XAnim needs BOTH the *.rsrc and the 
  809.     *.data in order to recognize and display the animation.
  810.   
  811.     The only exception to this is if the animation has been "flattened".
  812.     Essentially, all that this means is that the .rsrc and .data files
  813.     were merged into one file for export to a non-mac computer.
  814.     This file doesn't have any real naming conventions, but it is
  815.     usually something like .mov, .mv, .qt, etc(it is never .bin or .hqx). 
  816.     And it is rarely .data. If XAnim can't play it, then it's 95%
  817.     likely to be a *.data fork(that's missing a *.rsrc fork) and not
  818.     a flattened quicktime animation.
  819.  
  820.     Macunpack and hexbin can be found in the macutil archive. They
  821.     are available at the following locations:
  822.  
  823.         sumex-aim.stanford.edu:/info-mac/unix/macutil-20b1.shar
  824.         ftp.cwi.nl:/pub/macutil2.0b3.shar.Z
  825.         solaris.ims.ac.jp:/pub/unix/mac/macutil-20b1.shar
  826.  
  827.     Use archie to find other sites.
  828.  
  829.     Here's a quick blurb on macutils from the readme.
  830.  
  831.             o hexbin - a program to convert BinHex 4.0 to MacBinary;
  832.           it also converts uuencode (and UULite) files to their
  833.           native binary format; support for .dl, .hex, and .hcx
  834.           formats (all predecessors of BinHex 4.0) also exists
  835.  
  836.             o macunpack - a program to unpack PackIt, StuffIt,
  837.           Diamond, Compactor/Compact Pro, most StuffIt Classic
  838.           and StuffIt Deluxe, DiskDoubler, Zoom and LHarc/MacLHa
  839.           archives.
  840.  
  841.           It also decodes BinHex 5.0, MacBinary, uuencode, and
  842.           UNIX compress (ie: .Z suffix) files (as well as variants
  843.           of compress implemented by various Macintosh compress
  844.           programs).
  845.  
  846.  
  847.   TRANSFERING DIRECTLY FROM A MACINTOSH
  848.  
  849.     If you are transferring a quicktime animation directly from a 
  850.     Macintosh(ftp/fetch/gator/etc), you need to use the MacBinary mode.
  851.     This will archive all three resource forks(.info,.rsrc and .data) 
  852.     into a .bin file and transfer that. You must then use "macunpack -flv"
  853.     as described above.
  854.   
  855.     If you use Binary mode(as opposed to the MacBinary mode), ONLY the 
  856.     *.data file will be transferred. This *.data file is useless without
  857.     the *.rsrc file, unless it happens to be "flattened". If you don't
  858.     absolutely know this to be true, then use the MacBinary mode and 
  859.     extract with macunpack.
  860.  
  861.  
  862.   OTHER PROGRAMS
  863.  
  864.     mcvert is also capable of extracting the *.rsrc and *.data files
  865.     form a MacBinary file(*.bin). It doesn't support all of the
  866.     archival compression formats that macunpack does and I'm not
  867.     as familiar with it. Archie should be able to find it.
  868.  
  869.   CREATING A QUICKTIME FOR EXPORT ON A MACINTOSH
  870.  
  871.     Movieconverter, part of Apple's Quicktime Starter Kit (a commercial product)
  872.     can do this.  Save the movie as BOTH "Make self-contained" and "Playable
  873.     on non-Apple computers." 
  874.  
  875.  
  876.   If you have any other questions or problems trying to run 
  877.   quicktime animation using xanim I might be able to answer
  878.   them.
  879.  
  880. ------------------------------------------------------------------------------
  881.  
  882. Mark Podlipec  podlipec@wellfleet.com
  883. http://www.portal.com/~podlipec/home.html  "The XAnim Home Page"
  884.